<!DOCTYPE html>

<html>
  <head>
    <meta charset="utf-8">
    
    <title>Advanced F2PY usages &mdash; NumPy v1.18 Manual</title>
    
    <link rel="stylesheet" type="text/css" href="../_static/css/spc-bootstrap.css">
    <link rel="stylesheet" type="text/css" href="../_static/css/spc-extend.css">
    <link rel="stylesheet" href="../_static/scipy.css" type="text/css" >
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" >
    <link rel="stylesheet" href="../_static/graphviz.css" type="text/css" >
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../',
        VERSION:     '1.18.1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  false
      };
    </script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <script type="text/javascript" src="../_static/language_data.js"></script>
    <script type="text/javascript" src="../_static/js/copybutton.js"></script>
    <link rel="author" title="About these documents" href="../about.html" >
    <link rel="index" title="Index" href="../genindex.html" >
    <link rel="search" title="Search" href="../search.html" >
    <link rel="top" title="NumPy v1.18 Manual" href="../index.html" >
    <link rel="up" title="F2PY Users Guide and Reference Manual" href="index.html" >
    <link rel="next" title="Contributing to NumPy" href="../dev/index.html" >
    <link rel="prev" title="Using via numpy.distutils" href="distutils.html" > 
  </head>
  <body>
<div class="container">
  <div class="top-scipy-org-logo-header" style="background-color: #a2bae8;">
    <a href="../index.html">
      <img border=0 alt="NumPy" src="../_static/numpy_logo.png"></a>
    </div>
  </div>
</div>


    <div class="container">
      <div class="main">
        
	<div class="row-fluid">
	  <div class="span12">
	    <div class="spc-navbar">
              
    <ul class="nav nav-pills pull-left">
        <li class="active"><a href="https://numpy.org/">NumPy.org</a></li>
        <li class="active"><a href="https://numpy.org/doc">Docs</a></li>
        
        <li class="active"><a href="../index.html">NumPy v1.18 Manual</a></li>
        

          <li class="active"><a href="index.html" accesskey="U">F2PY Users Guide and Reference Manual</a></li> 
    </ul>
              
              
    <ul class="nav nav-pills pull-right">
      <li class="active">
        <a href="../genindex.html" title="General Index"
           accesskey="I">index</a>
      </li>
      <li class="active">
        <a href="../dev/index.html" title="Contributing to NumPy"
           accesskey="N">next</a>
      </li>
      <li class="active">
        <a href="distutils.html" title="Using via numpy.distutils"
           accesskey="P">previous</a>
      </li>
    </ul>
              
	    </div>
	  </div>
	</div>
        

	<div class="row-fluid">
      <div class="spc-rightsidebar span3">
        <div class="sphinxsidebarwrapper">
  <h3><a href="../contents.html">Table of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Advanced F2PY usages</a><ul>
<li><a class="reference internal" href="#adding-self-written-functions-to-f2py-generated-modules">Adding self-written functions to F2PY generated modules</a></li>
<li><a class="reference internal" href="#modifying-the-dictionary-of-a-f2py-generated-module">Modifying the dictionary of a F2PY generated module</a></li>
<li><a class="reference internal" href="#dealing-with-kind-specifiers">Dealing with KIND specifiers</a></li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="distutils.html"
                        title="previous chapter">Using via <code class="xref py py-obj docutils literal notranslate"><span class="pre">numpy.distutils</span></code></a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="../dev/index.html"
                        title="next chapter">Contributing to NumPy</a></p>
<div id="searchbox" style="display: none" role="search">
  <h4>Quick search</h4>
    <div>
    <form class="search" action="../search.html" method="get">
      <input type="text" style="width: inherit;" name="q" />
      <input type="submit" value="search" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
          <div class="span9">
            
        <div class="bodywrapper">
          <div class="body" id="spc-section-body">
            
  <div class="section" id="advanced-f2py-usages">
<h1>Advanced F2PY usages<a class="headerlink" href="#advanced-f2py-usages" title="Permalink to this headline">¶</a></h1>
<div class="section" id="adding-self-written-functions-to-f2py-generated-modules">
<h2>Adding self-written functions to F2PY generated modules<a class="headerlink" href="#adding-self-written-functions-to-f2py-generated-modules" title="Permalink to this headline">¶</a></h2>
<p>Self-written Python C/API functions can be defined inside
signature files using <code class="docutils literal notranslate"><span class="pre">usercode</span></code> and <code class="docutils literal notranslate"><span class="pre">pymethoddef</span></code> statements
(they must be used inside the <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">module</span></code> block). For
example, the following signature file <code class="docutils literal notranslate"><span class="pre">spam.pyf</span></code></p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!    -*- f90 -*-
python module spam
    usercode &#39;&#39;&#39;
  static char doc_spam_system[] = &quot;Execute a shell command.&quot;;
  static PyObject *spam_system(PyObject *self, PyObject *args)
  {
    char *command;
    int sts;

    if (!PyArg_ParseTuple(args, &quot;s&quot;, &amp;command))
        return NULL;
    sts = system(command);
    return Py_BuildValue(&quot;i&quot;, sts);
  }
    &#39;&#39;&#39;
    pymethoddef &#39;&#39;&#39;
    {&quot;system&quot;,  spam_system, METH_VARARGS, doc_spam_system},
    &#39;&#39;&#39;
end python module spam
</pre></div>
</div>
<p>wraps the C library function <code class="docutils literal notranslate"><span class="pre">system()</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">f2py</span> <span class="o">-</span><span class="n">c</span> <span class="n">spam</span><span class="o">.</span><span class="n">pyf</span>
</pre></div>
</div>
<p>In Python:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">spam</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">status</span> <span class="o">=</span> <span class="n">spam</span><span class="o">.</span><span class="n">system</span><span class="p">(</span><span class="s1">&#39;whoami&#39;</span><span class="p">)</span>
<span class="go">pearu</span>
<span class="go">&gt;&gt; status = spam.system(&#39;blah&#39;)</span>
<span class="go">sh: line 1: blah: command not found</span>
</pre></div>
</div>
</div>
<div class="section" id="modifying-the-dictionary-of-a-f2py-generated-module">
<h2>Modifying the dictionary of a F2PY generated module<a class="headerlink" href="#modifying-the-dictionary-of-a-f2py-generated-module" title="Permalink to this headline">¶</a></h2>
<p>The following example illustrates how to add a user-defined
variables to a F2PY generated extension module. Given the following
signature file</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!    -*- f90 -*-
python module var
  usercode &#39;&#39;&#39;
    int BAR = 5;
  &#39;&#39;&#39;
  interface
    usercode &#39;&#39;&#39;
      PyDict_SetItemString(d,&quot;BAR&quot;,PyInt_FromLong(BAR));
    &#39;&#39;&#39;
  end interface
end python module
</pre></div>
</div>
<p>compile it as <code class="docutils literal notranslate"><span class="pre">f2py</span> <span class="pre">-c</span> <span class="pre">var.pyf</span></code>.</p>
<p>Notice that the second <code class="docutils literal notranslate"><span class="pre">usercode</span></code> statement must be defined inside
an <code class="docutils literal notranslate"><span class="pre">interface</span></code> block and where the module dictionary is available through
the variable <code class="docutils literal notranslate"><span class="pre">d</span></code> (see <code class="docutils literal notranslate"><span class="pre">f2py</span> <span class="pre">var.pyf</span></code>-generated <code class="docutils literal notranslate"><span class="pre">varmodule.c</span></code> for
additional details).</p>
<p>In Python:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">var</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">var</span><span class="o">.</span><span class="n">BAR</span>
<span class="go">5</span>
</pre></div>
</div>
</div>
<div class="section" id="dealing-with-kind-specifiers">
<h2>Dealing with KIND specifiers<a class="headerlink" href="#dealing-with-kind-specifiers" title="Permalink to this headline">¶</a></h2>
<p>Currently, F2PY can handle only <code class="docutils literal notranslate"><span class="pre">&lt;type</span> <span class="pre">spec&gt;(kind=&lt;kindselector&gt;)</span></code>
declarations where <code class="docutils literal notranslate"><span class="pre">&lt;kindselector&gt;</span></code> is a numeric integer (e.g. 1, 2,
4,…), but not a function call <code class="docutils literal notranslate"><span class="pre">KIND(..)</span></code> or any other
expression. F2PY needs to know what would be the corresponding C type
and a general solution for that would be too complicated to implement.</p>
<p>However, F2PY provides a hook to overcome this difficulty, namely,
users can define their own &lt;Fortran type&gt; to &lt;C type&gt; maps. For
example, if Fortran 90 code contains:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">REAL</span><span class="p">(</span><span class="n">kind</span><span class="o">=</span><span class="n">KIND</span><span class="p">(</span><span class="mf">0.0</span><span class="n">D0</span><span class="p">))</span> <span class="o">...</span>
</pre></div>
</div>
<p>then create a mapping file containing a Python dictionary:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="s1">&#39;real&#39;</span><span class="p">:</span> <span class="p">{</span><span class="s1">&#39;KIND(0.0D0)&#39;</span><span class="p">:</span> <span class="s1">&#39;double&#39;</span><span class="p">}}</span>
</pre></div>
</div>
<p>for instance.</p>
<p>Use the <code class="docutils literal notranslate"><span class="pre">--f2cmap</span></code> command-line option to pass the file name to F2PY.
By default, F2PY assumes file name is <code class="docutils literal notranslate"><span class="pre">.f2py_f2cmap</span></code> in the current
working directory.</p>
<p>Or more generally, the f2cmap file must contain a dictionary
with items:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">&lt;</span><span class="n">Fortran</span> <span class="n">typespec</span><span class="o">&gt;</span> <span class="p">:</span> <span class="p">{</span><span class="o">&lt;</span><span class="n">selector_expr</span><span class="o">&gt;</span><span class="p">:</span><span class="o">&lt;</span><span class="n">C</span> <span class="nb">type</span><span class="o">&gt;</span><span class="p">}</span>
</pre></div>
</div>
<p>that defines mapping between Fortran type:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">&lt;</span><span class="n">Fortran</span> <span class="n">typespec</span><span class="o">&gt;</span><span class="p">([</span><span class="n">kind</span><span class="o">=</span><span class="p">]</span><span class="o">&lt;</span><span class="n">selector_expr</span><span class="o">&gt;</span><span class="p">)</span>
</pre></div>
</div>
<p>and the corresponding &lt;C type&gt;. &lt;C type&gt; can be one of the following:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">char</span>
<span class="n">signed_char</span>
<span class="n">short</span>
<span class="nb">int</span>
<span class="n">long_long</span>
<span class="nb">float</span>
<span class="n">double</span>
<span class="n">long_double</span>
<span class="n">complex_float</span>
<span class="n">complex_double</span>
<span class="n">complex_long_double</span>
<span class="n">string</span>
</pre></div>
</div>
<p>For more information, see F2Py source code <code class="docutils literal notranslate"><span class="pre">numpy/f2py/capi_maps.py</span></code>.</p>
</div>
</div>


          </div>
        </div>
          </div>
        </div>
      </div>
    </div>

    <div class="container container-navbar-bottom">
      <div class="spc-navbar">
        
      </div>
    </div>
    <div class="container">
    <div class="footer">
    <div class="row-fluid">
    <ul class="inline pull-left">
      <li>
        &copy; Copyright 2008-2019, The SciPy community.
      </li>
      <li>
      Last updated on Feb 20, 2020.
      </li>
      <li>
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.4.2.
      </li>
    </ul>
    </div>
    </div>
    </div>
  </body>
</html>